home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / util / shell / ViNCEd.lha / ViNCEd / Include / Autodocs / titlebar.doc next >
Text File  |  1998-09-27  |  11KB  |  302 lines
  1. TABLE OF CONTENTS
  2.  
  3. titlebar.image/--background--
  4. titlebar.image/titlebar.image
  5. titlebar.image/ObtainTBIClass
  6. titlebar.image/--background--                   titlebar.image/--background--
  7.  
  8. DESCRIPTION
  9.  
  10. The titlebar.image is a shared library which, when opened, adds to the system
  11. a public BOOPSI image class called "tbiclass". This class implements several
  12. images suitable for the use as imagery of gadgets added to the titlebar of
  13. a window, such as an "iconify" image, a "pop-up" image, and so on. Also, a
  14. general purpose "empty" (border-only) image is provided, to be used as the
  15. background of more specialized titlebar images.
  16.  
  17. The purpose of "tbiclass" is to offer developers an easy way to implement
  18. the most common additional titlebar gadgets without having to draw or
  19. code their imagery themselves, and with the added benefit of standardizing
  20. the size and appearance of this kind of gadgets. For instance, until now
  21. any developer needing an iconify gadget had to hard-code its imagery into
  22. his application, leading to a plethora of similar, but different, versions
  23. of the same gadget.
  24.  
  25. The library is freeware; if you use it, you are allowed to distribute it
  26. with your software, typically as a stand-alone file (you'll just have to
  27. add a section for it in your application's installation script).
  28.  
  29. Using "tbiclass" is very simple: you just need to open the titlebar.image
  30. library in order to add the class to the system, and then close it when you
  31. don't need the class anymore (and have freed all of its instances).
  32.  
  33. Once the class has been added to the system, you can use NewObject() in the
  34. usual way to create new "tbiclass" instances. See the "Class documentation"
  35. section to learn which tags are recognized by the class, as well as more
  36. information about the class in general.
  37.  
  38. Important note: a more refined version of "tbiclass" is also added to the
  39. system at boot time by the VisualPrefs utility (a patch to modify the look
  40. of the Amiga GUI). If the titlebar.image library, when it's opened, finds
  41. that a class named "tbiclass" already exists, it won't create another, but
  42. still will open successfully, so your code does NOT have to change to take
  43. this special case into account.
  44.  
  45. The only thing to remember is, you should NOT open the titlebar.image library
  46. if your program is launched in the Startup-sequence _before_ the line where
  47. VisualPrefs is usually started (which is just before IPrefs), or else the
  48. patch won't run correctly. If you absolutely need to place your program in
  49. the Startup-sequence before VisualPrefs/IPrefs, at least offer the user
  50. an option to avoid opening the titlebar.image library.
  51. Anyway, this shouldn't be a problem for the vast majority of applications...
  52.  
  53.  
  54. CLASS DOCUMENTATION
  55.  
  56. Class:        tbiclass
  57. Superclass:   imageclass
  58. Include File: <images/titlebar.h>
  59.  
  60. This is a class of images suitable for use as imagery of gadgets added to
  61. a window titlebar. As of version 40, there are 6 possible "tbiclass" images
  62. to choose from:
  63.  
  64. POPUPIMAGE          A MUI "pop-up" titlebar gadget image
  65. MUIIMAGE            A MUI "settings" titlebar gadget image
  66. SNAPSHOTIMAGE       A MUI "snapshot" titlebar gadget image
  67. ICONIFYIMAGE        An "iconify" titlebar gadget image
  68. PADLOCKIMAGE        A DirOpus "padlock" titlebar gadget image
  69. TBFRAMEIMAGE        A general-purpose empty titlebar gadget image
  70.  
  71. These image types are an extension to those already offered by "sysiclass";
  72. in fact, "tbiclass" is used mostly the same way as "sysiclass" (see below
  73. for its methods and attributes).
  74.  
  75. It's worth noticing that all "tbiclass" image instances will have an
  76. Image->LeftEdge value of -1. This shouldn't be modified, and you should
  77. place your titlebar gadgets accordingly. The reason for this apparently
  78. strange behavior is that Intuition titlebar gadget images, too, work
  79. this way, and we should try to stay as compatible with Intuition as
  80. possible.
  81.  
  82. Also, make sure you adjust your gadget's size if necessary, to adapt it
  83. to the returned image's size.
  84.  
  85. There are actually two versions of this class: a disk-based one, implemented
  86. by the freely distributable "titlebar.image" library, and another, more
  87. refined, added to the system by the VisualPrefs program at boot time.
  88. Applications needing this class should always ship with the "titlebar.image"
  89. library, and use it without worrying about the presence of VisualPrefs in the
  90. system: if it's running, its "tbiclass" version will be used automatically.
  91.  
  92. The _only_ exception to this rule is when your application is run in the
  93. Startup-sequence before VisualPrefs; in this case, you should offer the
  94. user an option to avoid opening "titlebar.image", otherwise the disk-based
  95. version of the class would be added to the system and VisualPrefs wouldn't
  96. be able to add its own version. This is, however, a very unlikely scenario;
  97. in all foreseeable cases, an application opening windows shouldn't be run
  98. so early in the Startup-sequence.
  99.  
  100. New Methods:
  101.  
  102. None.
  103.  
  104. Changed Methods:
  105.  
  106. OM_NEW - After creation of the image by the superclass, this method
  107. initializes the "tbiclass" instance data on the basis of the contents
  108. of the attributes tag list.
  109.  
  110. OM_DISPOSE - This method frees all the resources allocated in the OM_NEW
  111. method.
  112.  
  113. OM_SET - This method allows to change a few of the image attributes and
  114. checks their bounds integrity.
  115.  
  116. OM_GET - This method allows to retrieve the value of the most relevant
  117. image attributes.
  118.  
  119. IM_DRAW - This method does the actual rendering of the image, taking into
  120. account its various attributes and the screen's DrawInfo pens.
  121.  
  122. IM_DRAWFRAME - Like IM_DRAW, but uses the size specified in the impDraw
  123. message rather than the one in the image structure.
  124.  
  125. Attributes:
  126.  
  127. SYSIA_DrawInfo (IS) - This is absolutely mandatory. You MUST pass a DrawInfo
  128.                       pointer to "tbiclass" or NewObject() will fail.
  129.  
  130. SYSIA_Which (ISG) - To specify which image you want; currently there are six
  131.                     image types, defined in <images/titlebar.h>: POPUPIMAGE,
  132.                     MUIIMAGE, SNAPSHOTIMAGE, ICONIFYIMAGE, PADLOCKIMAGE and
  133.                     TBFRAMEIMAGE.
  134.  
  135. IA_Width, IA_Height (ISG) - Only recognized by the TBFRAMEIMAGE type; the
  136.                             other image types ignore them and always have
  137.                             the same size of the depth gadget image.
  138.  
  139. SYSIA_ReferenceFont (IS) - This is only recognized by the TBFRAMEIMAGE type;
  140.                            the other image types ignore it and always have
  141.                            the same height of the depth gadget image. It's
  142.                            also ignored if IA_Height is explicitly used.
  143.  
  144.  
  145. PROGRAMMING EXAMPLE
  146.  
  147. An example of usage of "titlebar.image" and "tbiclass" could be given by
  148. the following code fragment:
  149.  
  150.    ...
  151.    #include "images/titlebar.h"
  152.    #include "clib/titlebarimage_protos.h"
  153.    #include "pragmas/titlebarimage_pragmas.h"
  154.  
  155.    ...
  156.    
  157.    struct Library *TitlebarImageBase;
  158.  
  159.    ...
  160.  
  161.    /* Open the library */
  162.    
  163.    if (!(TitlebarImageBase = OpenLibrary("Images/titlebar.image",40)))
  164.    {
  165.       ComplainAndExit();
  166.    }
  167.  
  168.    ...
  169.  
  170.    /* Create the image */
  171.  
  172.    if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
  173.                                                   SYSIA_DrawInfo,dri,
  174.                                                   TAG_END)))
  175.    {
  176.       iconifyimage = builtin_iconifyimage;  /* If really needed... */
  177.    }
  178.  
  179.    /* Use the image */
  180.  
  181.    gad->GadgetRender = iconifyimage;
  182.    ...
  183.  
  184.    /* Free the image */
  185.  
  186.    if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
  187.  
  188.    ...
  189.    
  190.    /* Close the library */
  191.    
  192.    CloseLibrary(TitlebarImageBase);
  193.    
  194.    ...
  195.  
  196. A complete example program can also be found in the distribution archive.
  197.  
  198.  
  199. TO DO
  200.  
  201. Future releases should add the following features:
  202.  
  203.  o More image types.
  204.  
  205.  o Some more code optimization.
  206.  
  207. And of course, I'm open to any suggestion about how to improve the class.
  208.  
  209.  
  210. AUTHOR
  211.  
  212. Massimo Tantignone
  213. Via Campagnoli, 4
  214. 28100 Novara (NO)
  215. ITALY
  216.  
  217. E-mail: tanti@intercom.it
  218. Web:    http://www.intercom.it/~amigaws
  219.  
  220. titlebar.image/titlebar.image                   titlebar.image/titlebar.image
  221.  
  222.    NAME
  223.       titlebar.image -- create an image suitable for titlebar gadg